//  Copyright (c) 2002-2010 "Neo Technology,"
//      Network Engine for Objects in Lund AB [http://neotechnology.com]
// 
//  This file is part of Neo4j.
//  
//  Neo4j is free software: you can redistribute it and/or modify
//  it under the terms of the GNU Affero General Public License as
//  published by the Free Software Foundation, either version 3 of the
//  License, or (at your option) any later version.
//  
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU Affero General Public License for more details.
//  
//  You should have received a copy of the GNU Affero General Public License
//  along with this program. If not, see <http://www.gnu.org/licenses/>.

#region Using Directives

using System.Collections.Generic;

#endregion
namespace org.neo4j.graphdb
{
	//using EmbeddedGraphDatabase = org.neo4j.kernel.EmbeddedGraphDatabase;

    /// <summary>  
    /// The main access point to a running Neo4j instance. The most common
    ///  implementation is the <seealso cref="EmbeddedGraphDatabase"/> class, which is used to
    ///  embed Neo4j in an application. Typically, you would create an
    ///  <code>EmbeddedGraphDatabase</code> instance as follows:  
    ///  <pre>
    ///  <code>GraphDatabaseService graphDb = new EmbeddedGraphDatabase( "var/graphDb" );
    ///  // ... use Neo4j
    ///  graphDb.<seealso cref="shutdown() shutdown()"/>;</code>
    ///  </pre>
    ///  GraphDatabaseService provides operations to {@link #enableRemoteShell enable
    ///  the shell}, <seealso cref="createNode() create nodes"/>, {@link #getNodeById(long) get
    ///  nodes given an id}, get the <seealso cref="getReferenceNode() reference node"/> and
    ///  ultimately <seealso cref="shutdown() shutdown Neo4j"/>.
    ///  <p>
    ///  Please note that all operations that read or write to the graph must be
    ///  invoked in a <seealso cref="Transaction transactional context"/>. Failure to do so will
    ///  result in a <seealso cref="NotInTransactionException"/> being thrown. </summary>
	public interface IGraphDatabaseService
	{ 
        ///<summary> 
        ///  Creates a new node.
        ///  </summary>
        /// <returns> the created node. </returns>
		Node CreateNode();   
        ///<summary> 
        /// Looks up a node by id.
        ///  </summary>
        /// <param name="id"> the id of the node </param>
        /// <returns> the node with id <code>id</code> if found </returns>
        /// <exception cref="NotFoundException"> if not found </exception>
		Node GetNodeById(long id);  
        ///<summary>  
        /// Looks up a relationship by id.
        ///  </summary>
        /// <param name="id"> the id of the relationship </param>
        /// <returns> the relationship with id <code>id</code> if found </returns>
        /// <exception cref="NotFoundException"> if not found </exception>
		Relationship GetRelationshipById(long id);
        ///<summary>  
        /// Returns the reference node, which is a "starting point" in the node
        /// space. Usually, a client attaches relationships to this node that leads
        /// into various parts of the node space. For more information about common
        /// node space organizational patterns, see the design guide at <a
        /// href="http://wiki.neo4j.org/content/Design_Guide"
        /// >wiki.neo4j.org/content/Design_Guide</a>.
        ///  </summary>
        /// <returns> the reference node </returns>
        /// <exception cref="NotFoundException"> if unable to get the reference node </exception>
		Node GetReferenceNode();
        ///<summary> 
        ///  Returns all nodes in the node space.
        ///  </summary>
        /// <returns> all nodes in the node space </returns>
		IEnumerable<Node> GetAllNodes();
        ///<summary> 
        ///  Returns all relationship types currently in the underlying store.
        /// Relationship types are added to the underlying store the first time they
        /// are used in a successfully commited {@link Node#createRelationshipTo
        /// node.createRelationshipTo(...)}. Note that this method is guaranteed to
        /// return all known relationship types, but it does not guarantee that it
        /// won't return <i>more</i> than that (e.g. it can return "historic"
        /// relationship types that no longer have any relationships in the node
        /// space).
        ///  </summary>
        /// <returns> all relationship types in the underlying store </returns>
        IEnumerable<RelationshipType> GetRelationshipTypes(); 
        ///<summary> 
        ///  Shuts down Neo4j. After this method has been invoked, it's invalid to
        /// invoke any methods in the Neo4j API and all references to this instance
        /// of GraphDatabaseService should be discarded. </summary>
		void Shutdown();
        ///<summary> 
        ///  Enables remote shell access (with default configuration) to this Neo4j
        /// instance, if the Neo4j <a
        /// href="http://components.neo4j.org/neo4j-shell/">shell component</a> is
        /// available on the classpath. This method is identical to invoking
        /// <seealso cref="enableRemoteShell(Map) enableRemoteShell( null )"/>.
        ///  </summary>
        /// <returns> <code>true</code> if the shell has been enabled,
        ///         <code>false</code> otherwise (<code>false</code> usually
        ///         indicates that the <code>shell</code> jar dependency is not on
        ///         the classpath) </returns>
		bool EnableRemoteShell();
        ///<summary> 
        ///  Enables remote shell access to this Neo4j instance, if the Neo4j <a
        /// href="http://components.neo4j.org/neo4j-shell/">Shell component</a> is
        /// available on the classpath. This will publish a shell access interface on
        /// an RMI registry on localhost (with configurable port and RMI binding
        /// name). It can be accessed by a client that implements
        /// <seealso cref="org.neo4j.shell.ShellClient"/> from the Neo4j Shell project.
        /// Typically, the <code>neo4j-shell</code> binary package is used (see <a
        /// href="http://neo4j.org/download">neo4j.org/download</a>).
        /// <p>
        /// The shell is parameterized by a map of properties passed in to this
        /// method. Currently, two properties are used:
        /// <ul>
        /// <li><code>port</code>, an <seealso cref="Integer"/> describing the port of the RMI
        /// registry where the Neo4j shell will be bound, defaults to
        /// <code>1337</code>
        /// <li><code>name</code>, the <seealso cref="string"/> under which the Neo4j shell
        /// will be bound in the RMI registry, defaults to <code>shell</code>
        /// </ul>
        ///  </summary>
        /// <param name="initialProperties"> a set of properties that will be used to
        ///            configure the remote shell, or <code>null</code> if the
        ///            default properties should be used </param>
        /// <returns> <code>true</code> if the shell has been enabled,
        ///         <code>false</code> otherwise (<code>false</code> usually
        ///         indicates that the <code>shell</code> jar dependency is not on
        ///         the classpath) </returns>
        /// <exception cref="ClassCastException"> if the shell library is available, but one (or
        ///             more) of the configuration properties have an unexpected type </exception>
        /// <exception cref="IllegalStateException"> if the shell library is available, but the
        ///             remote shell can't be enabled anyway </exception>
		bool EnableRemoteShell(Dictionary<string, object> initialProperties);
        ///<summary> 
        ///  Starts a new transaction and associates it with the current thread.
        ///  </summary>
        /// <returns> a new transaction instance </returns>
		Transaction BeginTx();
	}
}